Conversation Object

Overview

The Conversation object is an ActiveX automation library object. It is the core of all AgentX communications. It provides a peer-to-peer link between two network nodes through a transaction-oriented shared dictionary. Use of Conversation objects is common to all AgentX-based applications, however the Remote and AgentX controls normally manage all interactions with the Conversation objects.

Conversation Object Example

The following sample source code gives an idea of how Conversation objects are used. Note all error handling has been removed for clarity.

' Make a local variable of the appropriate type.
Dim Talker as Conversation
' Connect to machine "DEMO" through an AgentX control instance.
Set Talker = AgentXTalker.Connect("DEMO")
 
' Assign the string "This is a test." to the key "Test".
Talker.SetData "Test", "This is a test."
 
' Assign the integer value 10 to the key "UsefulValue".
Talker.SetData "UsefulValue", 10
 
' Send changed values (all, in this case) to remote machine.
Talker.Send

This example shows a complete AgentX transaction. After acquiring a Conversation object from an AgentX control, the program assigns two values – one string, one integer – to two different keys in the Conversation. When calling the Send method on the Conversation object, all of the changed data keys (in this case, all of the data keys) are sent to the remote machine so that both machines' Conversation objects contain the same keys and data.

It is important to note that Conversation object variables must always use the Dim keyword to set their type. It is also important to use the Set keyword when assigning to a Conversation object variable.

Methods

ClearAllKeys

ClearAllKeys()

This method removes all of the keys and data in a local Conversation. Like the ClearKey method, only the local data is affected.

ClearKey

ClearKey(Key as String)

This method removes a named key and its data from the local Conversation. This method only affects the local copy of the data and will not clear the remote end, even on a call to Send. Clearing a key which does not exist is a trappable error.

Connect

Connect(Machine as String) as Conversation

This connects to the named destination machine. If a connection is already in place, it is closed down and all of the keys are made dirty in preparation for a new connection. See the Send method for details on dirty keys.

GetData

GetData(Key as String) as Variant

This method returns the data value matching the given key. The data value returned can be of any type. It is a trappable error, code 380 (vbInvalidPropertyValue) to call this method for a key which does not exist. The names of the keys in a conversation can be retrieved using the For ... Each syntax

EXAMPLE
Iterating through keys:

Dim conv as new Conversation
conv.SetData(“newkey“, “value“)
Dim key as String
For Each key in conv
   Debug.Print conv.GetData(key)
Next

Note that the keys may not be returned in the order in which they were originally added

IsChanged

IsChanged(Key as String) as Long

This method returns 0 if the given key has not changed since it was initially set. It returns a non-zero value if the given key has changed since it was initially set. It is an error to call this method for a key which does not exist.

LockConversation

LockConversation()

This prevents a Conversation object from being altered until UnlockConversation is called. For each call to LockConversation there must be a matching call to UnlockConversation.

ResetConversation

ResetConversation()

This method clears all keys and shuts down any connections to a remote Conversation object. This method should be called on any live Conversation objects before shutting down an application.

Send

Send()

This method sends all newly added or changed (dirty) keys in the local Conversation object to the remote machine. It then clears the dirty status of the sent keys. The dirty keys are the only ones sent to minimize network traffic. If there are no dirty keys, the method returns without sending any data at all.

SetData

SetData(Key as String, Data as Variant)

This method associates a data value of any type with a passed key. This data can later be retrieved by using an identical string in the GetData method. Keys are case-sensitive.

UnlockConversation

UnlockConversation()

This unlocks a previously locked Conversation. There must be one UnlockConversation call for each LockConversation call in a given code path.